The Epic Collection

home *** CD-ROM | disk | FTP | other *** search

/ The Epic Collection / Epic Collection, The (Epic Marketing)(1996).iso / lsdtools / lsd120.dms / lsd120.adf / docs / Z-LIST.DOC.pp / Z-LIST.DOC

Wrap

Text File | 1990-09-13 | 33KB | 760 lines

Z-List V1.0 User Manual Copyright © 1993 Grégoire Jean-Christophe All rights reserved Release Date: 12 June 1993 SHAREWARE Compatible with Hypercat * * OUTLAWS PRODUCTION * * This Program is dedicated to my friend Koen Peetermans 0] Table Of Contents ==================== x. Read Me First ! .......................... Do it then ! 1. Copyright - Disclaimer ................... Bah... 2. Registration ............................. Money ? 3. No Lame Protection ....................... Protection ?! 4. Some Technical Toughts ................... Skip this ! 5. What is Z-List ? ......................... Better read that... 6. Why did I write Z-List ? ................. Good question ! 7. The Package .............................. Registrate to be sure ! 8. Compatibility & Bugs ..................... Usual boring stuff... 9. The Author - Me ! ........................ Shame or fame ?! 10. Special Regards .......................... Feel concerned ? 11. Upgrade Plans ............................ The story isn't over... 12. Multi-Tasking ............................ Don't cry baby... 13. Limits ................................... Aaargh !!! 14. Using The ReqTools Requesters ............ Again ? 15. Compatibility with Hypercat .............. What now ? 16. Getting Started .......................... The most interesting ?... 17. Keyboard Shortcuts ....................... Interesting... 18. Using the string gadgets ................. Interesting too... 19. History .................................. 'Fast read' last changes 20. Little note to Human Interface ........... Kindda private words... How did I write so much ?! x] Read Me First ================ Z-List is my personal contribution to the OUTLAWS who give me total support on their lines. You may consider this program as an OUTLAWS production and can always get the latest version prior on Outlaws Bulletin Boards if you have access. I repeat that ALL Outlaws members can get a registrated version from me for free (I don't supply the disk !). Simply contact me and give me your full name and adress + the disk. Membership will be verificated, don't mess with your future on Amiga... 1] Copyright - Disclaimer ========================= This program is distributed in the hope that it will be useful, but without any warranty, without even the implied warranty of merchantability or fitness for a particular purpose. Z-List is shareware. You may distribute it without any problem as long as you don't earn money with it. Send me at least 10 US $ for the shareware fee if you use Z-List. Lower fees are accepted, but no registration can be asked ! This doc and Z-Converter (+ its doc) MUST be distributed with the executable Z-List. The executable and non-executable parts of this software package may NOT be altered by any means (this includes editing, reprogramming, and resourceing), except archiving and crunching. The author is in no way liable for any changes made to any part of the package, or consequences thereof as he is in no way liable for damages or loss of data directly or indirectly caused by this software. The Z-List package is copyright © 1993 by GREGOIRE Jean-Christophe. GREGOIRE Jean-Christophe, 64 Frans Timmermansstraat, B-1600 Sint Pieters Leeuw, BELGIUM. Z-List requires the ReqTools library which is copyright © Nico François. The library MUST be present on the disk used to spread Z-List. The Z-List package may be released in public domain disk libraries, compilation disks, club newsletters or any other kind of disk with the exception of commercially sold disks. Special permission is hereby granted to include Z-List in Public-Domain collections such as Fred Fish's Amiga Library and CAM. 2] Registration =============== You should send me at least 10 US $ if you use this program. I will send you in return a registrated version with your name, etc... (the last version of course) and a public version (may be spread). Your personal version won't pop up the 2 enervating requesters about the shareware fee at startup ! Refer to the chapter 'No Lame Protection' for more about this registrated version. I offer a registration service for all gifts of 20 US $ (more is good too). Each time I release a new version, I send it to you (they'll be numerous...). Group registrations are also possible. Send your 10 US $ + 5 US $ for each friend (and his adress) and all members of your 'association' will get a personal version. A registration service is also possible. This costs 20 US $ + 10 US $ for each new friend. All versions are sent to the responsible who wrote and paid for the group. I reserve the right to stop improving Z-List at any moment without further notice. I also reserve the right to stop the registration service at any moment (don't worry, all this is just for my protection...). When you send money to registrate, send your full name and adress. No P.O.Box please, I won't answer. NB: If you have a nice sister here in Belgium, I might offer you the registration... All Outlaws members, Fraxion members and Nuclear Holocaust members can get a registrated version from me for free (I don't supply the disk !) if they contact me and give me their full name and adress + the disk. All my other friends too of course... Memberships will be verificated, don't mess with your future on Amiga... 3] No Lame Protection ===================== Alot of friends proposed me to remove some 'unimportant' functions in the public version of Z-List. I don't wanna do this. However, I found out another nice system to force people to registrate: the public version uses slower sorting algorithms than the registrated version (the algorithm isn't the slowest, I don't like garbage, but it can take up to a minute to sort 1000 records... The first slow algorithm thought for the public version took up to 30 minutes, be happy !). If you need extreme speed, pay ! 4] Some Technical Thoughts ========================== Z-List has been fully created in Assembler on an A2000 kickstart 2.04 with a 50MB HD and 3 megs of memory. The source code is about 12000 lines long, 600000 bytes big and it took me about 5 months to develop it, (long) holidays included ! Assembler is really the easiest programming language... 5] What is Z-List ? =================== Z-List is an attempt to make the best disk-listing utility and should be the standard in disk lists ! I insist on the fact that Z-List is NOT made to encourage piracy !!! You can edit records in 3 parts, which should be, I think, the name (first column), the type (second column) and the number (third column). You can so list what you want. You can list your games and other disks for example, and give a number to each of your disks. But if you for example own a library, you can classify your books the same way. Applications are 'numerous'. Z-List has been largely inspired by HYPERCAT made by Ian Whu in 1988. 6] Why did I write Z-List ?! ============================ I often used HYPERCAT under 1.3. Once the kickstart 2.x arrived, I realised that it was really ugly (!) and that it could be done better. Then, a friend of mine made a program in the same style, but in GFA Basic. The program did what it had to do but was not good enough to conquer the world (!). I hope he'll appreciate this demonstration of power, I definitively beat him (don't under-estimate the work put in Z-List, Human, you don't know, you really don't know how far I am and had to be). Alot of Amiga users seem to need a GOOD disk-lister, and it seems to be very difficult to find. I have seen alot of strange lists, sometimes typed in ASCII-text, sometimes with text writers, and even with programs like Pen-Pal ! I really believe alot of you will be happy to have my program ! 7] The Package ============== The package includes the following files. If you don't have all this, write to me for the full package. Z-List .................................... The program Z-List.info ............................... The icon Z-List.Doc ................................ This document Z-List.Doc.info ........................... Its icon Z-Converter ............................... Hypercat List Converter Z-Converter.info .......................... Its icon Z-Converter.Doc ........................... Its document Z-Converter.Doc.info ...................... The document's icon ... and the ReqTools Library V38 (not for Kick 1.3) which can be found in the Libs directory. The nice Z-Converter, Z-Converter.Doc, Z-List and Z-List.Doc icons were drawn by my friend Falco. Thanks ! 8] Compatibility & Bugs ======================= Z-List has been roughly tested and has proven to be stable in every day use. If you ever encountered a bug, send me (please) a bug report including what occured, when, and which material you use. You will get the next version of Z-List. I advise you to state all details about the list you were using. If I can't reproduce the bug, I can't fix it... Z-List should work on any machine working under kickstart 2.x or 3.x. The ReqTools library needed by Z-List will make the test, so if you try to launch Z-List under 1.3, the ReqTools library will refuse to work, so my program will refuse to work too. Easy. Z-List is made for both NTSC & PAL and will automatically adapt its size to fit the full screen. KNOWN PROBLEMS: * Z-List seems to encounter some problems when opening its screen on A4000 (so on 1200 too I think) when your system is running in special viewmodes. The screen isn't actually centered anymore because my OpenScreen() is changed by the system to open a DBLPAL screen. I will correct this after having read a little bit more about the new viewmodes. * Z-List uses Alerts to warn you when 'terrible' errors occur. This also seems to give ugly results on 1200 and 4000. I will change that into requesters for the next release. * In the Insert/Modify Record windows, you should normally be able to pass from a string gadget to another by pressing ENTER, and the first string gadget is always active when the window pops up. I've found out that it doesn't work on all computers, don't cry if it doesn't work on yours ! I can't control this... it's a ROM function ! * Something really strange now... When you have printer problems like no paper, printer off line or printer turned off, you normally get a WB requester with the 2 famous gadgets Resume-Cancel. With my program, you don't get it on all computers ! I didn't get it on my computer, but friends of mine got it ! So, what should think ??? Anyway, don't be afraid, the errors are well handled: the program waits the usual 30 seconds and then abort. Sorry for those who don't have the possibility to resume... 9] The author - me ! ==================== There's not much to say. I am 21 years old and I am student in industrial informatic (computer science in good english I heard). Maybe one day I will be graduated as programmer-analyst specialised in electronic, robotic and artificial intelligence. Who knows ? 10] Special Regards =================== I take here the opportunity to greet the following people, and thank them for what they are (in no special order, although...): * Did/Outlaws (Come on boy, Felix awaits your intro...) * Felix/Outlaws (next year together ?!...) * Toxic/Outlaws (I finally have my US Robotics... With my keyboard, it'll be easier to chat !) * Gandalf/Outlaws (ready for the dentro ?) * Quantum/Outlaws (keep up the good work, you're a true Elite !) * Uninvited/Fraxion (your game is really good !) * Koen Peetermans * Flinny * Falco * Nico François * Human Interface * Stephane Brun * Alexandre Reis * Jim Maciorowski * John Lohmeyer * Colette Marc (Your father's attitude is intolerable and this kind of lamer is generally banished of my life. Sorry for including you too in my lamers list, it was not your fault) * All Nuclear Holocaust Sorry for the ones I forgot ! Here are mega-thanx to my ßeta-testers (in no particular order): - Koen Peetermans (Keep up the lazyness !!!!) - Belgium Thanx for the tricks & tips ! (and the numerous suggestions !) - Jim Maciorowski - USA - Falco - Belgium Thanx to Nico François for registrating me as ReqTools developper, the phone discussions, the advices (printer ?! ahahah !), etc... Boy, it was very nice getting in touch ! Probably one of the nicest Amiga freaks... I also wanna thank the shop AMIGA CITY for letting me use the A4000 and A1200 when I needed to. Thanks also for the commercial support. 11] Upgrade Plans ================= Here's a quick overview of my dreams: * V1.01 to Vx.xx: - Maybe parameters at startup in CLI to simultaneously load Z-List and a list. - Possibility to fusion lists. - Font choosable. - Possibility to save your preferences. - A proportional gadget in the main window. Another nice way to scroll through your list ! This will be optional. - All AmigaDOS errors detourned. No more (fucking) horrible AmigaDOS error requester ! (and better error reports !). - Use of the locale library for you to have Z-List in your own language. It's up to you... Contact me if you want to make the translation. - Better paging possibilities for printing like page number, header string and auto page skip each x lines. - Possibility to print only a part of a list for all three printing options. - Better keyboard shortcuts: menu included ! and ReqTools style (gadgets selcted too). - Possibility to make a global type replacement (replace given type by another string). - Possibility to list all the files of a given disk or a given directory (all the files are put in the current list). - Possibility to print labels (selecting a record ?) - 'On-line' comments to inform the user about the actions currently done by Z-List. - A depth gadget or a sleep option. - Z-List's directory taken as current directory. - 'Really Quit' requester only when the list is not saved. - Faster disk operations (yes, this is possible !) - Faster sortings (only for registered users...) - Very Soon... The documentation in French and Dutch (and Z-List too, refer to the locale library) Contact me if you wanna translate the docs in your language. - Alot of optimisations. Due to a lack of time, I haven't been able to do that before the first release, but Z-List really needs that ! - Some bug fixes, maybe... I'm waiting for your suggestions ! 12] Multi-Tasking ================= Z-List is 'not' forseen to work simultaneousy with other programs, no Screen Dragbar and depth gadget are provided. If you need some background music or anything else, launch it before ! If you absolutely need to do something else while Z-List is running, press together RIGHT AMIGA KEY + M. This puts the current screen in the background (like screen depth gadget). 13] Limits ========== Yes, there are limits ! The first one depends on you: the most memory you have, the most records you'll be able to create in a list. In case of memory lack, you won't be allowed to edit more records (silly, èh). The record number (which you input) is limited to 9999. I had to put a limit, I chose 9999. I think that's enough. Who does have 9999 games, or even disks ? If I get some letters asking me to add one more figure (limit then put to 99999 !), I can eventually do it. Attention !!! I am just talking about the possible values for the number which is taken as counter. However, you can use the same number for several records and edit as much records as memory allows. 14] Using The ReqTools Requesters ================================= Z-List will use ReqTools Requesters for special actions. I'm not going to explain how to use them, but here are some tricks & tips: - The words displayed in bold in some gadgets mean that this gadget will be activated too if you press return. This is what people call a "keyboard shortcut" ! - Other Requesters offer underlined characters in the gadgets. When you press together the right Amiga key and the underlined letter, the gadget is selected as if you had clicked on it. Return also selects the appropriate option accordingly to the current status. - Hopeless, the ReqTools Requesters take as mouse pointer the one used by your system. I can't control this, sorry about that. - Using the File Requester (Save & Load), you can also click on your right mouse button to get the drives. Use arrow keys up and down to make appear and/or move the selection bar. ENTER to select, or cancel if nothing was selected. - PLEASE, DO NOT click on the depth gadgets !!!! The Requesters will be displayed behind the main window and you won't be able to access them since I don't provide depth gadgets ! The only chance you have is not to click (to keep the requester activated) and use the keyboard shortcuts to control it (actually better close it with ok or cancel, or return). For those who know what I'm talking about, I could not use a backdrop main window (special reason). I'm not really looking for a solution. - If you are running Z-List and get a requester saying "Please Insert Volume ENV:", this is normal: ReqTools is just looking for its preferences in this volume (which should be created and assigned in any normal WorkBench 2.x startup-sequence). This will happen only once if you don't reboot and launch Z-List several times. You have 2 possibilities: get rid of the requester ! or assign this volume in the startup-sequence of the disk you are running from if you wanna get rid of it for the rest of your life... 15] Compatibility with Hypercat =============================== Although I wrote everywhere that Z-List is compatible with Hypercat, Z-List is not properly compatible with Hypercat (so, don't try to load a Hypercat list from Z-List !). I simply provide a converter called "Z-Converter" to convert Hypercat lists in the Z-List format (this is possible because both programs use approximatively the same system, don't ask me a converter for your Word Processor !). Please, refer to the Z-Converter User Manual for more about this. This isn't actually very important, I'm sure only a few people will need it... 16] Getting Started =================== Z-List can be either started from your WorkBench or the CLI/SHELL. In WorkBench, simply click on its icon. In CLI, simply type its name (which should normally be "Z-List"). No parameters are needed (yet). You can see the version of Z-List on its screen and in the About window, but you can directly ask that in CLI/SHELL using the AmigaDOS command VERSION. Type this to get the version: Version <filename> ,so this in our case: Version Z-List Once Z-List is loaded, you have several choices possible. Some options are ghosted (unavailable), but they will be enabled accordingly to the number of records entered. The most often used functions are offered as gadgets in the main window for quick access, but numerous other functions are put in a pull-down menu which you access by clicking and holding the right mouse button. A complete description of the functions follows. You can also click on a record on the print field to select it. The "Delete Record" function will then be enabled. If you click a second time on it, the record window will appear with all the records details put in the string gadgets to let you modify the record. As usual, the number may not be empty, and the old one will be kept as long as you don't change it. If you absolutely need to clear the record, choose "Delete Record" ! If you select 'CANCEL', no action will be taken (ever heard this somewhere...). To get rid of the enlightment, simply click a second time and then choose 'CANCEL' in the modifications window. I'll try to find another system later. Every time you open a window, the 'screen' is locked for safety. The only way to unlock it is leaving the currently opened window. Menu Project: ------------- - New: This will clear all your list. A requester will first appear to ask a confirmation. - Load: Calls a file requester to let you load a list previously created with Z-List. If there is already a list in memory, Z-List will simply remove it. Remember that, Z-List still doesn't warn you... If there is not enough memory to load the entire list, the action will be canceled and no single record will be loaded (silly, silly !). In the future, if there is already a list in memory, you will be asked wether you wanna fusion the lists, clear the currently loaded one or cancel. - Save: Calls a file requester to let you save your list. - Quit: This lets you exit the program. A little requester will ask you a confirmation and remind you that unsaved work will be lost. It would be very easy to check wether the list is saved or not, but I'm lazy ! Menu Sort: ---------- - Name: This lets you sort alphabetically your list on the name. - Type: The same, but on the type. - Number: This lets you sort the list on the numbers in crescent order. Once the job is done, Z-List displays the first page (like TOP). If your list was already sorted, the screen will flash to warn you that no action was taken. As stated above in this doc, the fast routines are in the registrated version... Menu Find: ---------- - Name: Let you find the record which contains the given string as name. If you terminate your string with a star, the first record beginning with this string will be printed at the top of the screen. If you give the full string, the first record containing this string as name will be printed at the top of the screen. The next records are the logical alphabetical continuation only if your list is sorted ! Inputing only a star or nothing has the same effect as CANCEL, that's to say nothing ! If the string doesn't exist in the list, the screen will flash to warn you. - Type: The same, but the search is made in the types of the records. - Number: The same, but the numbers are considered. Be aware that you can't input a star (because you can't type anything else than a number). If you wanna cancel the search and are too lazy to click on the CANCEL gadget, simply enter nothing in the string gadget and hit RETURN. Menu Print: ----------- - Name: Allows to send your list to your printer. Only the names will be printed. In the future, you'll be able to select only a part of the list. - Name & Type: Allows to send your list to your printer. Only the names and types will be printed. In the future, you'll be able to select only a part of the list. - Name & Type & Number: Allows to send your list to your printer. The full records will be printed exactly as they are presented on screen. In the future, you'll be able to select only a part of the list. There is a gadget for you to abort the printing. You can select it by clicking on it or using the combination of keys CTRL-A, but not with ENTER. Selecting this causes the printing to be immediately stopped, but if your printer has some memory on board (buffer), the buffer will of course be printed before. Menu More: ---------- - Insert Record: Pops up a window for you to enter the record details. You have there to insert a name which will be printed in column 1, a type which will be printed in column 2 and a number (with numeric keypad) which will be printed in column 3. When you click on 'OK', the record is stored in memory and printed on screen (if there is place, else scroll). The name and type strings may be empty, but the number not. If it is, the number 1 will be placed instead. The number is auto incremented for the next time you call the window, and the name and type are cleared. Everything for easy editing ! If you click on 'CANCEL', the name and type are cleared and the number is buffered for the next time you call the window. Nothing of course will be stored or printed. If the number is empty, the number 1 will also be placed instead. When the window appears, the first string gadget contains the cursor. If you press RETURN, the second does. If you press RETURN again, the third does. Pressing RETURN again puts again the cursor in the first string gadget, etc... - Delete Record: Before you can call this function, you must select a record (click on it). This function simply removes a record from the list. Deleting a record reminding alone in the list has naturally the same effect as "Project/New". Deleting the last record of the last page (printed on the first line, naturally the very last entry) causes Z-List to display the top of the list after. - Info: Here we come to an interesting part... This window gives you the number of records in the list (what's not, I agree, very useful), but also says if they are sorted (+ how), and finally gives the size of the available memory. I advice to regularly call this function to check the available memory. A comment is even printed to warn you when you're running low on memory. My program is normally able to handle all errors to avoid any crash, and most of all memory problems, but you never know... Now, you can see when it's really time to save to prevent any problem. For sure, you should be very careful when you just have about 100bytes left... In the future, the window will also tell the number of the selected record if one is selected. This is useful if you need to print only a part of your list. Menu Preferences: ----------------- - Set Colours: This submenu lets you choose between the standards screen colours of the WB 2.x (palette presets). - Palette: This is a little palette for you to create your own screen colours. - Printer Setup: This lets you choose between Draft and Letter quality. This option will be greatly enhanced. Some gadgets offer some more options: - About: Really wonder what it is ? - Forward: Scrolls to the end of the list page by page. - Backward: The same, but to the beginning of the list. - Top: Brings the first page of the list on screen. - Bottom: Brings the last page of the list on screen. The gadget "Record" has the same effect as the menu item "Insert Record". 17] Keyboard Shortcuts ====================== - Cursor down: Scrolls to the end of the list record by record. This isn't still 'fluent' (doesn't work when you keep pressing), I'll fix it for the next release. - Cursor up: The same, but to the beginning of the list. - Cursor Left: Same as gadget "Backward". - Cursor Right: Same as gadget "Forward". HELP has the same function as the gadget About, and ESC has the same function as the gadget and the menu item Quit. You'll certainly see that a character is underlined in each gadget. When you press together CTRL and the underlined key, the same action is taken, as if you had clicked. In the windows containing only one gadget (About, Info & Printer SetUp), you can also use RETURN. The 'Find xxxx' windows also allow the use of RETURN, the appropriate action will be taken. Windows like Quit or Clear asking you a specific answer don't allow the use RETURN. The windows used to edit or modify your records already use RETURN to pass from one string gadget to another, so you also have to use only the CTRL combinations. Problems to be resolved: ------------------------ * When a string gadget is active, you CAN'T use the keyboard shortcuts ! (This is because the string gadget uses the keyboard, easily said). I'm working on this, it's possible to do it... * Like in ReqTools, I would like the gadgets to be selected at the same time. That will be easily done after a little message conversion. Thanx Nico ! * The Amiga Style User guide says that programs shouldn't use a combination of keys but only one key. I do it because it would be impossible if there was a string gadget active, and it's easier for the user to have only one possibility (always CTRL...). 18] Using the string gadgets ============================ Here are again some nice keyboard shortcuts: - CTRL+u -> Clears the content +w -> Clears to the first blank - cursor must be at the end +x -> Also clears the content - CTRL+a -> Puts cursor at the beginning - CTRL+z -> Puts cursor at the end - CTRL+h -> Has the same effect as backspace - CTRL+m -> Has the same effect as RETURN Ok, I hope you'll like my program ! 19] History =========== * V1.0ß: Never released, for testing purpose. * V1.0: First public release, June 1993. - Replaced the sorting routines in the public release. Sorting time falled down from 30 minutes to 1 minute for 1000 records. They had to be slow but not that slow ! - Made new sorting algorithm for the registrated version. Still not the QuickSort due to a lack of time. 20] Note to Human Interface =========================== I hate it when you look at me like at a little apprentice... and I hate you when you don't even look at my programs. Just try to reach my level... if it's not too far for you !!!